feat(optimization): persist and revalidate field envelope evidence - #4312

Ready for independent review — 2026-10-15

Exact head e2f06ce756f05b5b55048750cec58876eb138f08 now passes all ten published workflows and all 22 Build/Test/Javadoc jobs, including Java 8 on Ubuntu and Windows. Its #4333/#4328/#4326 prerequisites are merged. Marked ready for review at the user's request for ordered integration; no source changes or new independent approval are claimed. The accountable owner/domain and serialized-contract reviews described below remain required before merge. Earlier statements to keep draft pending CI are historical.

Master integration — 2026-10-15

Integrated head e2f06ce756f05b5b55048750cec58876eb138f08 incorporates master a346faa1f13adfc95c99dff18e90a348d8725d28; verified tree 94c461161424d71a528ee1a075bf25f86a173501. Resolved independent task-log insertions by retaining both histories and regenerated the coverage inventory. The proposal guard and replay behavior were tested against the merged compressor changes.

Validation: 6 Java integration tests and 68 Python tests passed, zero failures. Stable direct formatting, both hook stages, documentation search, regenerated coverage/check and whitespace checks passed. Documentation impact: retained the existing implementation guides and task-log entries from both branches; no new API, physics or tolerance change is introduced by this integration. Earlier evidence below applies to its recorded checkpoints. Integration follows the user's explicit instruction to merge in dependency order; new-head hosted CI is tracked separately.

Coordination and merge gates — 2026-10-14

Reviewed published head: ac80719e08d28d39d5890da94cbc5967382ee685.

The resume/current-guard repair is now published. It restores frozen user restrictions, reruns cheap validation on resume and binds ledger publication to the exact proposals accepted by the current guard. All 13 new regressions fail the prior head; the repaired production/continuous/living suites pass 99 tests with one existing optional-DOCX skip. Mandatory local gates and independent technical re-review pass. Fresh hosted CI is still running; prior-head dependency failures do not qualify this new head.

Require process/engineering owner coverage, independent maintainer review of serialized evidence and old-reader compatibility, and independent engineering-domain review of advice acceptance/invalidation. A qualified independent maintainer may cover both independent roles. Added JSON evidence fields alone do not automatically require an NRC: existing opportunity statuses and requires_approval remain. Record whether the current/stale evidence semantics establish a new governed approval/lifecycle contract; if so, an accepted NRC is required. Agent review is not human approval.

Integration: Prefer corrected #4328 → #4326 → this repaired PR. Keep exact action/vector replay and early evidence invalidation; do not duplicate compressor physics or introduce another ledger.

Summary

Advance #4188 under #3154 by carrying accepted-point operating-envelope evidence through the existing #4187 continuous-task guard and append-only ledger, invalidating it whenever the field/host operating definition changes, and revalidating only from a newly replayed safe point.

• bind ordered accepted action identifiers and values exactly to proposal setpoints;
• fail closed on stale/mismatched optimizer evidence, malformed or duplicate slices, incomplete point recovery, inconsistent counts/runtime provenance, and a failed guard;
• map production/injection route line-ups, controlled reservoir boundaries, mapped rotating-equipment power, common-shaft speed/power, driver limits, shared host-power limits, and other operating limits into the existing evidence graph;
• supersede stale unfinished advice before replacement evaluation;
• preserve revalidation_of lineage through unsafe cycles that intentionally produce no proposal;
• expose current/stale evidence in the Living Report;
• reuse merged feat(field): switch canonical route configurations #4314/feat(field): exercise live injection route configurations #4317 route and reservoir ownership plus feat(field): integrate mapped rotating equipment power #4322 mapped-power aggregation without adding another model, solver, constraint system, or store.

Added on the current head

The combined ten-well field-to-facility acceptance case now includes a configured curve-backed injection utility on the canonical field-network graph. Its solved power is included by ProcessModel.getPower(...) beside both compressor casings, and the existing shared-resource evidence cross-checks the exact area total.

Accepted-point evidence now carries three complete slices: choke, reversible separator-pressure routing, and host/shared-power response. Every point must restore and reconverge the baseline and retain finite available shared-power evidence.

The persistent acceptance workflow versions mapped network power, common-shaft power/speed, driver limit, and shared plant power limit. A non-finite mapped demand or power-limit breach invalidates the incumbent and yields no replacement; a later safe limit creates fresh evidence and resumes the prior lineage.

Safety and engineering behavior

Envelope-backed advice is accepted only when cycle identity, embedded optimizer evidence, ordered actions, finite setpoints, slice identities/axes, requested/completed points, state restoration, baseline reconvergence, evaluation counts, runtime totals, and advisory status reconcile.

Route selectors remain discrete process actions. Reservoir pressure remains a model input owned by WellFlow.ReservoirLayer. Pump/compressor charts and solved power remain owned by the canonical network/equipment and ProcessModel implementations. No physical constraint, tolerance, convergence, map, fracture, restoration, replay, or power limit is weakened.

Failed-cycle repair and integration — 2026-10-14

Previous repair head: 2ad11a044af88c67375ea8d0f4925b9ac9e7af5f
Previous tested/published tree: cf37841517f808cec317d007960e1ca00e0011c2
Parents: previous PR head d469208 and current master d28b180.

The review reproduced a defect: after an operating-definition change, a malformed optimizer proposal or optimizer exception could fail the guard, skip ledger publication, and leave the previous advice marked current. Four of the new regression cases failed on the old implementation.

Invalidation now runs in the evidence stage before model/optimizer/guard execution, and when restoring evidence on resume. It marks historical evidence non-current, supersedes eligible unfinished advice, remains idempotent across retries, preserves fresh replacements when resuming, and leaves persisted state unchanged in a dry run. The guard still controls creation of new advice. Custom plans must retain evidence-first ordering; the ledger fallback alone cannot invalidate early if a guard failure skips that stage.

Integration preserves master's renamed workflows, Maven configuration and shared evidence-source fixture. The original Java implementation is unchanged by this repair. The branch has no remaining Git merge conflicts.

Resume-safety repair — 2026-10-14

An interruption after a completed guard could restore the optimizer's original proposals while skipping the filtering and frozen user restrictions that made them safe. Resume now reuses expensive model/optimizer work, restores the cycle's frozen inputs, and reruns gates, constraints and guard before ledger publication. Missing or malformed input checkpoints block advice.

The ledger binds publication to the exact proposal content accepted by the current-cycle guard. Old-cycle approvals, post-guard setpoint mutations, and removal of evidence fields cannot revive rejected advice. No model, solver, store, constraint tolerance, or physical operating limit is added or weakened.

Current head: ac80719e08d28d39d5890da94cbc5967382ee685
Exact tested and published tree: ac3b381cf271c62c73927108af197e3b1c8ca2e5

Validation and integration

• Thirteen new regression cases fail the previous 2ad11a0 implementation; repaired continuous/production/living suites: 99 passed, 1 existing optional DOCX skip.
• Independent agent technical re-review reproduced rejection of stale, mutated and evidence-stripped proposals and acceptance of an unchanged detached copy. This is not a human maintainer approval.
• Direct Spotless apply/check, both all-files pre-commit stages, documentation search (788 Markdown pages and one HTML), unchanged generated engineering inventory and whitespace checks pass.
• Earlier broader Java and workflow results remain historical evidence for their tested commits; they are not represented as validation of this new head.

Fresh hosted CI and the applicable independent domain/maintainer review are pending. Keep draft. Preferred process integration order is #4328 → #4326 → #4312 so persistent advice consumes qualified network and compressor results. #4328's companion repair now rejects an unsuccessful or non-finite mapped compressor solve.

Documentation impact

Updated the continuous-task guide, external-optimizer integration guide, and continuous-improvement skill for mapped network power, common-shaft/driver/shared-power definition changes, fail-closed invalidation, and lineage recovery. The merged #4322 SURF guide remains the canonical map/power integration reference.

The failed-cycle repair and integration are recorded in docs/development/TASK_LOG.md. The guides and continuous-improvement skill now explain early invalidation, recovery/resume behavior, dry runs and the ordering required for custom plans.

Coordination and scope boundary

• Field-to-facility production optimization: coupled wells, routing, equipment constraints and operating envelope #4188 / [Campaign] Industrial-scale ProcessSystem and ProcessModel optimization #3154: active field-to-facility implementation track.
• [Roadmap] Continuous engineering task solving: persistent resume, living status and final reports #4187: extends its guard, evidence graph, report, and append-only ledger; no competing persistence architecture.
• [Campaign] ProcessSystem and ProcessModel performance roadmap #2939: retains explicit evaluation/runtime provenance and performance ownership.
• feat(field): switch canonical route configurations #4314 / feat(field): exercise live injection route configurations #4317 / feat(field): integrate mapped rotating equipment power #4322 / [Campaign] State-of-the-art well, subsea gathering, injection and SURF network modelling/design #4228: consumes canonical production/injection route, reservoir, topology, mapped-power, and host-power contracts without taking over their physics.
• [Feature] Coordinate compressor load sharing with surge, choke and shared-driver limits #4146, [Feature] Qualify compression-train optimization for interstage cooling, HP2 speed and recycle/pressure coordination #4147, [Feature] Qualify compressor maps under composition, temperature and pressure changes #4148: consumes compressor/common-shaft acceptance evidence without changing compressor physics.

Next dependency

After review/merge, extend the same exact-head contract across lifecycle/time slices where separator/scrubber capacity and qualified compressor-map/driver/shared-power bottlenecks move. Keep map qualification with #4146–#4148, network physics with #4228, and measured execution performance with #2939.

Refs #4188, #3154, #4187, #2939, #4146, #4147, #4148, #4228, #4314, #4317, #4322.

Coordinated integration dependency

Use #4333 → #4328 → #4326 → this PR for the process/optimizer lane. #4333 isolates the shared mixing-rule accumulator race; #4326 is stacked on it. Preserve this PR's evidence/resume checks and requalify its final integrated head after those process changes. CI and the accountable reviews under GOVERNANCE.md remain merge gates.